chrome.userScripts

Mô tả

Sử dụng API userScripts để thực thi tập lệnh của người dùng trong ngữ cảnh Tập lệnh của người dùng.

Quyền

userScripts

Để sử dụng API tập lệnh của người dùng, chrome.userScripts, hãy thêm quyền "userScripts" vào manifest.json và "host_permissions" cho các trang web mà bạn muốn chạy tập lệnh.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Phạm vi cung cấp

Chrome 120 trở lên MV3 trở lên

Khái niệm và cách sử dụng

Tập lệnh người dùng là một đoạn mã được chèn vào trang web để sửa đổi giao diện hoặc hành vi của trang web đó. Không giống như các tính năng tiện ích khác, chẳng hạn như Tập lệnh nội dung và API chrome.scripting, API Tập lệnh của người dùng cho phép bạn chạy mã tuỳ ý. API này là bắt buộc đối với các tiện ích chạy tập lệnh do người dùng cung cấp và không thể được vận chuyển trong gói tiện ích của bạn.

Bật tính năng sử dụng API userScripts

Sau khi tiện ích của bạn nhận được quyền sử dụng API userScripts, người dùng phải bật một nút bật/tắt cụ thể để cho phép tiện ích của bạn sử dụng API. Tùy theo phiên bản Chrome mà tuỳ chọn bật/tắt cụ thể bắt buộc và hành vi của API khi bị tắt sẽ khác nhau.

Sử dụng quy trình kiểm tra sau đây để xác định nút bật/tắt mà người dùng cần bật, ví dụ: trong quá trình giới thiệu người dùng mới:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version > 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

Các phần sau đây mô tả các nút bật/tắt và cách bật các nút này.

Các phiên bản Chrome trước phiên bản 138 (Chế độ nhà phát triển bật/tắt)

Là nhà phát triển tiện ích, bạn đã bật chế độ Developer (Nhà phát triển) trong quá trình cài đặt Chrome. Người dùng cũng phải bật Chế độ nhà phát triển.

Bạn có thể sao chép và dán các hướng dẫn sau vào tài liệu của tiện ích cho người dùng

  1. Chuyển đến trang Tiện ích bằng cách nhập chrome://extensions trong một thẻ mới. (Theo thiết kế, bạn không thể liên kết các URL chrome://.)

  2. Bật Chế độ nhà phát triển bằng cách nhấp vào nút bật/tắt bên cạnh Chế độ nhà phát triển.

    Trang Tiện ích của Chrome, trong đó nút bật/tắt Chế độ nhà phát triển được làm nổi bật

    Trang tiện ích (chrome://extensions)

Chrome phiên bản 138 trở lên (nút bật/tắt Cho phép tập lệnh của người dùng)

Nút bật/tắt Allow User Scripts (Cho phép tập lệnh của người dùng) nằm trên trang chi tiết của từng tiện ích (ví dụ: chrome://extensions/?id=YOUR_EXTENSION_ID).

Bạn có thể sao chép và dán hướng dẫn sau vào tài liệu của tiện ích cho người dùng:

  1. Chuyển đến trang Tiện ích bằng cách nhập chrome://extensions trong một thẻ mới. (Theo thiết kế, bạn không thể liên kết các URL chrome://.)
  2. Nhấp vào nút "Chi tiết" trên thẻ tiện ích để xem thông tin chi tiết về tiện ích đó.
  3. Nhấp vào nút bật/tắt bên cạnh Cho phép tập lệnh của người dùng.
Nút bật/tắt Cho phép tập lệnh của người dùng trên trang chi tiết về tiện ích
Nút bật/tắt Cho phép tập lệnh của người dùng (chrome://extensions/?id=abc...)

Kiểm tra xem API có hoạt động hay không

Bạn nên kiểm tra như sau để xác định xem userScripts API có được bật hay không, vì API này hoạt động trong tất cả phiên bản Chrome. Quy trình kiểm tra này sẽ cố gắng gọi một phương thức chrome.userScripts() luôn thành công khi có API. Nếu lệnh gọi này gửi lỗi, thì API sẽ không hoạt động:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Làm việc trong các thế giới riêng biệt

Cả tập lệnh người dùng và tập lệnh nội dung đều có thể chạy trong một thế giới riêng biệt hoặc trong thế giới chính. Một thế giới riêng biệt là một môi trường thực thi mà trang lưu trữ hoặc các tiện ích khác không thể truy cập. Điều này cho phép tập lệnh của người dùng thay đổi môi trường JavaScript mà không ảnh hưởng đến trang lưu trữ hoặc tập lệnh nội dung và người dùng của các tiện ích khác. Ngược lại, trang lưu trữ hoặc tập lệnh người dùng và tập lệnh nội dung của các tiện ích khác sẽ không thấy tập lệnh người dùng (và tập lệnh nội dung). Các tập lệnh chạy trong thế giới chính có thể truy cập vào các trang lưu trữ và các tiện ích khác, đồng thời hiển thị với các trang lưu trữ và các tiện ích khác. Để chọn thế giới, hãy truyền "USER_SCRIPT" hoặc "MAIN" khi gọi userScripts.register().

Để định cấu hình chính sách bảo mật nội dung cho thế giới USER_SCRIPT, hãy gọi userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Nhắn tin

Giống như tập lệnh nội dung và tài liệu ngoài màn hình, tập lệnh người dùng giao tiếp với các phần khác của tiện ích bằng cách sử dụng thông báo (nghĩa là chúng có thể gọi runtime.sendMessage() và runtime.connect() như bất kỳ phần nào khác của tiện ích). Tuy nhiên, các sự kiện này được nhận bằng trình xử lý sự kiện chuyên dụng (nghĩa là không sử dụng onMessage hoặc onConnect). Các trình xử lý này được gọi là runtime.onUserScriptMessage và runtime.onUserScriptConnect. Trình xử lý chuyên dụng giúp dễ dàng xác định thông báo từ tập lệnh của người dùng, đây là một ngữ cảnh ít đáng tin cậy hơn.

Trước khi gửi thông báo, bạn phải gọi configureWorld() với đối số messaging được đặt thành true. Xin lưu ý rằng bạn có thể truyền cả đối số csp và messaging cùng một lúc.

chrome.userScripts.configureWorld({
  messaging: true
});

Thông tin cập nhật về tiện ích

Các tập lệnh của người dùng sẽ bị xoá khi một tiện ích cập nhật. Bạn có thể thêm lại các trình xử lý đó bằng cách chạy mã trong trình xử lý sự kiện runtime.onInstalled trong worker dịch vụ tiện ích. Chỉ phản hồi lý do "update" được truyền đến lệnh gọi lại sự kiện.

Ví dụ:

Ví dụ này được lấy từ mẫu userScript trong kho lưu trữ mẫu của chúng tôi.

Đăng ký tập lệnh

Ví dụ sau đây cho thấy một lệnh gọi cơ bản đến register(). Đối số đầu tiên là một mảng các đối tượng xác định các tập lệnh cần đăng ký. Có nhiều tuỳ chọn hơn những tuỳ chọn được hiển thị ở đây.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Loại

ExecutionWorld

Môi trường JavaScript để tập lệnh của người dùng thực thi.

Enum

"MAIN"
Chỉ định môi trường thực thi của DOM, đây là môi trường thực thi được chia sẻ với JavaScript của trang lưu trữ.

"USER_SCRIPT"
Chỉ định môi trường thực thi dành riêng cho tập lệnh của người dùng và được miễn trừ khỏi CSP của trang.

InjectionResult

Chrome 135 trở lên

Thuộc tính

  • documentId

    chuỗi

    Tài liệu liên kết với hoạt động chèn.

  • error

    chuỗi không bắt buộc

    Lỗi (nếu có). error và result loại trừ lẫn nhau.

  • frameId

    số

    Khung liên kết với hoạt động chèn.

  • kết quả

    bất kỳ không bắt buộc nào

    Kết quả của quá trình thực thi tập lệnh.

InjectionTarget

Chrome 135 trở lên

Thuộc tính

  • allFrames

    boolean không bắt buộc

    Liệu tập lệnh có được chèn vào tất cả các khung trong thẻ hay không. Giá trị mặc định là sai. Điều này không được đúng nếu bạn chỉ định frameIds.

  • documentIds

    string[] không bắt buộc

    Mã của các documentId cụ thể cần chèn vào. Bạn không được đặt thuộc tính này nếu đã đặt frameIds.

  • frameIds

    number[] không bắt buộc

    Mã nhận dạng của các khung cụ thể cần chèn vào.

  • tabId

    số

    Mã của thẻ cần chèn.

RegisteredUserScript

Thuộc tính

  • allFrames

    boolean không bắt buộc

    Nếu đúng, thuộc tính này sẽ chèn vào tất cả các khung, ngay cả khi khung đó không phải là khung trên cùng trong thẻ. Mỗi khung được kiểm tra độc lập theo các yêu cầu về URL; khung sẽ không chèn vào các khung con nếu không đáp ứng các yêu cầu về URL. Mặc định là false, nghĩa là chỉ khớp khung trên cùng.

  • excludeGlobs

    string[] không bắt buộc

    Chỉ định mẫu ký tự đại diện cho các trang mà tập lệnh người dùng này KHÔNG được chèn vào.

  • excludeMatches

    string[] không bắt buộc

    Loại trừ các trang mà tập lệnh người dùng này sẽ được chèn vào. Hãy xem phần Mẫu khớp để biết thêm thông tin chi tiết về cú pháp của các chuỗi này.

  • id

    chuỗi

    Mã của tập lệnh người dùng được chỉ định trong lệnh gọi API. Thuộc tính này không được bắt đầu bằng "_" vì thuộc tính này được đặt trước làm tiền tố cho mã tập lệnh được tạo.

  • includeGlobs

    string[] không bắt buộc

    Chỉ định mẫu ký tự đại diện cho các trang mà tập lệnh người dùng này sẽ được chèn vào.

  • js

    ScriptSource[] không bắt buộc

    Danh sách các đối tượng ScriptSource xác định nguồn của tập lệnh cần chèn vào các trang trùng khớp. Bạn phải chỉ định thuộc tính này cho ${ref:register} và khi chỉ định, thuộc tính này phải là một mảng không trống.

  • khớp với

    string[] không bắt buộc

    Chỉ định những trang mà tập lệnh người dùng này sẽ được chèn vào. Hãy xem phần Mẫu khớp để biết thêm thông tin chi tiết về cú pháp của các chuỗi này. Bạn phải chỉ định thuộc tính này cho ${ref:register}.

  • runAt

    RunAt không bắt buộc

    Chỉ định thời điểm chèn tệp JavaScript vào trang web. Giá trị ưu tiên và mặc định là document_idle.

  • thế giới

    ExecutionWorld không bắt buộc

    Môi trường thực thi JavaScript để chạy tập lệnh. Mặc định là `USER_SCRIPT`.

  • worldId

    chuỗi không bắt buộc

    Chrome 133 trở lên

    Chỉ định mã nhận dạng thế giới của tập lệnh người dùng để thực thi. Nếu bạn bỏ qua, tập lệnh sẽ thực thi trong thế giới tập lệnh người dùng mặc định. Chỉ hợp lệ nếu world bị bỏ qua hoặc là USER_SCRIPT. Các giá trị có dấu gạch dưới ở đầu (_) được đặt trước.

ScriptSource

Thuộc tính

  • mã

    chuỗi không bắt buộc

    Một chuỗi chứa mã JavaScript cần chèn. Bạn phải chỉ định đúng một trong hai thuộc tính file hoặc code.

  • tệp

    chuỗi không bắt buộc

    Đường dẫn của tệp JavaScript cần chèn so với thư mục gốc của tiện ích. Bạn phải chỉ định đúng một trong hai thuộc tính file hoặc code.

UserScriptFilter

Thuộc tính

  • mã nhận dạng

    string[] không bắt buộc

    getScripts chỉ trả về các tập lệnh có mã nhận dạng được chỉ định trong danh sách này.

UserScriptInjection

Chrome 135 trở lên

Thuộc tính

  • injectImmediately

    boolean không bắt buộc

    Liệu quá trình chèn có được kích hoạt trong mục tiêu càng sớm càng tốt hay không. Xin lưu ý rằng điều này không đảm bảo rằng quá trình chèn sẽ xảy ra trước khi tải trang, vì trang có thể đã tải xong vào thời điểm tập lệnh đạt đến mục tiêu.

  • Danh sách các đối tượng ScriptSource xác định nguồn tập lệnh cần chèn vào mục tiêu.

  • mục tiêu

    InjectionTarget

    Thông tin chi tiết chỉ định mục tiêu để chèn tập lệnh.

  • thế giới

    ExecutionWorld không bắt buộc

    "Thế giới" JavaScript để chạy tập lệnh. Mặc định là USER_SCRIPT.

  • worldId

    chuỗi không bắt buộc

    Chỉ định mã nhận dạng thế giới của tập lệnh người dùng để thực thi. Nếu bạn bỏ qua, tập lệnh sẽ thực thi trong thế giới tập lệnh người dùng mặc định. Chỉ hợp lệ nếu world bị bỏ qua hoặc là USER_SCRIPT. Các giá trị có dấu gạch dưới ở đầu (_) được đặt trước.

WorldProperties

Thuộc tính

  • csp

    chuỗi không bắt buộc

    Chỉ định csp thế giới. Giá trị mặc định là csp thế giới `ISOLATED`.

  • nhắn tin

    boolean không bắt buộc

    Chỉ định xem có hiển thị API nhắn tin hay không. Mặc định là false.

  • worldId

    chuỗi không bắt buộc

    Chrome 133 trở lên

    Chỉ định mã nhận dạng của thế giới tập lệnh người dùng cụ thể cần cập nhật. Nếu không được cung cấp, hãy cập nhật các thuộc tính của thế giới tập lệnh người dùng mặc định. Các giá trị có dấu gạch dưới ở đầu (_) được đặt trước.

Phương thức

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Định cấu hình môi trường thực thi `USER_SCRIPT`.

Thông số

  • các tài sản

    WorldProperties

    Chứa cấu hình thế giới tập lệnh của người dùng.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

execute()

Lời hứa Chrome 135 trở lên 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

Chèn một tập lệnh vào ngữ cảnh mục tiêu. Theo mặc định, tập lệnh sẽ chạy tại document_idle hoặc ngay lập tức nếu trang đã tải. Nếu bạn đặt thuộc tính injectImmediately, tập lệnh sẽ chèn mà không cần chờ, ngay cả khi trang chưa tải xong. Nếu tập lệnh đánh giá thành một lời hứa, trình duyệt sẽ đợi lời hứa đó được thực hiện và trả về giá trị thu được.

Thông số

Giá trị trả về

  • Promise<InjectionResult[]>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Trả về tất cả tập lệnh người dùng được đăng ký động cho tiện ích này.

Thông số

  • filter

    UserScriptFilter không bắt buộc

    Nếu được chỉ định, phương thức này chỉ trả về các tập lệnh người dùng khớp với tập lệnh đó.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (scripts: RegisteredUserScript[]) => void

Giá trị trả về

  • Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getWorldConfigurations()

Lời hứa Chrome 133 trở lên 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Truy xuất tất cả cấu hình thế giới đã đăng ký.

Thông số

Giá trị trả về

  • Promise<WorldProperties[]>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Đăng ký một hoặc nhiều tập lệnh người dùng cho tiện ích này.

Thông số

  • các tập lệnh

    RegisteredUserScript[]

    Chứa danh sách tập lệnh người dùng cần đăng ký.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

resetWorldConfiguration()

Lời hứa Chrome 133 trở lên 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Đặt lại cấu hình cho thế giới tập lệnh của người dùng. Mọi tập lệnh chèn vào thế giới bằng mã nhận dạng đã chỉ định sẽ sử dụng cấu hình thế giới mặc định.

Thông số

  • worldId

    chuỗi không bắt buộc

    Mã của thế giới tập lệnh người dùng cần đặt lại. Nếu bạn bỏ qua thuộc tính này, hệ thống sẽ đặt lại cấu hình của thế giới mặc định.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Huỷ đăng ký tất cả tập lệnh người dùng được đăng ký động cho tiện ích này.

Thông số

  • filter

    UserScriptFilter không bắt buộc

    Nếu được chỉ định, phương thức này sẽ chỉ huỷ đăng ký các tập lệnh người dùng khớp với phương thức đó.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Cập nhật một hoặc nhiều tập lệnh người dùng cho tiện ích này.

Thông số

  • các tập lệnh

    RegisteredUserScript[]

    Chứa danh sách tập lệnh người dùng cần cập nhật. Một thuộc tính chỉ được cập nhật cho tập lệnh hiện có nếu thuộc tính đó được chỉ định trong đối tượng này. Nếu có lỗi trong quá trình phân tích cú pháp tập lệnh/xác thực tệp hoặc nếu mã nhận dạng được chỉ định không tương ứng với một tập lệnh đã đăng ký đầy đủ, thì không có tập lệnh nào được cập nhật.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.